/*
 * To change this template, choose Tools | Templates
 * and open the template in the editor.
 */

package org.ranch.api.service;

import java.util.List;

import org.ranch.model.Person;
import org.ranch.model.User;
import org.ranch.model.exception.RanchOperationFailedException;
import org.ranch.model.exception.RanchValidationException;

/**
 * Interface to add a person into the system
 */
public interface  PersonService {

    /**
     * gets a person based on their firstname
     * 
     * @param firstName
     *            string person's firstName
     * @return Person or null if no much found
     */
    Person findPersonByFirstName(String firstName);

    /**
     * saves a given person
     * 
     * @param person
     * @throws RanchValidationException
     *             thrown when the validation of a person fails.
     */
    void savePerson(Person person) throws RanchValidationException;

    /**
     * gets a list of all Persons in the system
     * 
     * @return
     */
    List<Person> getPersons();

    /**
     * deletes a given person from the system
     * 
     * @param person
     * @throws RanchOperationFailedException
     *             thrown when the delete operation fails
     */
    void deletePerson(Person Person) throws RanchValidationException;

    /**
     * finds persons whose firstname(s) are like the query provided. This means
     * that if a query like 'ct' is provided, all users who begin with the ct
     * characters are returned
     * 
     * @param query
     * @return
     */
    List<Person> findPersonByFirstname(String query);

    /**
     * gets a person with a given Id
     * 
     * @param personId
     * @return
     */
    Person getPersonById(String personId);


    /**
     * gets a list of persons on a given page number
     * 
     * @param pageNo
     * @return
     */
    List<Person> getPerson(Integer pageNo);

    /**
     * 
     * @return
     */
    int getTotalNumberOfPerson();

    /**
     * gets total number of persons who meet the search criteria
     * 
     * @param query
     * @return
     */
    int getNumberOfPersonsInSearch(String query);
    
    /**
     * Validate a user before saving a person
     * 
     * @param user
     * @return
     * @throws RanchValidationException 
     */
    User validateUser(User user) throws RanchValidationException;

    /**
     * finds  person by a given id
     * 
     * @param id
     * @return
     */
    Person findPersonById(String id);
    
    void validatePerson(Person person) throws RanchValidationException; 
}
